Introduction
This sections describes the Event Handling system. It will show you how it works and how you can use it to listen for security related events.
Events are a nice way to allow additional logic to be executed in response to certain security events. This can be very useful if you want to:
PicketBox's event system also allows you to use the Event Manager to fire specific security events for your application. You are not tied to only the event types that are provided, you can write your own events and fire them along your application code, leveraging the notification level for security related events in your application.
Handling Events
The event system design is very simple, basically what you need to know is that event handlers can be any class. The only restriction is that the class must have one or more methods annotated with the @EventObserver annotation.
Security Event Handler example
public class UserAuthenticationEventHandler {
@EventObserver
public void onSuccessful(UserAuthenticatedEvent event) {
// do something
}
@EventObserver
public void onUnSuccessful(UserNotAuthenticatedEvent event) {
// do something
}
@EventObserver
public void onFailed(UserAuthenticationFailedEvent event) {
// do something
}
}
The code above demonstrates how to create a class to handle some specific security events. Note that each method is annotated with the @EventObserver annotation.
Now, you just need to register this handler when building the PicketBox configuration as follows.
Registering the event handler during the configuration
ConfigurationBuilder configurationBuilder = new ConfigurationBuilder();
UserAuthenticationEventHandler eventHandler = new UserAuthenticationEventHandler();
configurationBuilder.authentication().eventManager().handler(eventHandler);
// proceed with the configuration, create and start the PicketBoxManager
Firing Events
Firing Security Events using the EventManager
PicketBoxManager picketBoxManager = // get the manager
// gets the event manager from the PicketBox manager
PicketBoxEventManager eventManager = picketBoxManager.getEventManager();
// fires the event
eventManager.raiseEvent(new MyOwnSecurityEvent());
Supported Events
The following tables enlist all event types and handlers and their description.
User Authentication
Event
|
Description
|
UserAuthenticatedEvent
|
Fired when the user is authenticated.
|
UserNotAuthenticatedEvent
|
Fired when an user is invalid and is not authenticated.
|
UserPreAuthenticationEvent
|
Fired at the beginning of the authentication process.
|
UserAuthenticationFailedEvent
|
Fired if some error occurs during the user authentication.
|
Logout
Event
|
Description
|
UserLoggedOutEvent
|
Fired when the user is logged out.
|
Auditing
Event
|
Description
|
PreAuditEvent
|
Fired before the audit record is processed by the audit provider.
|
PostAuditEvent
|
Fored after the audit record is processed by the audit provider.
|
Session Management
Event
|
Description
|
SessionCreatedEvent
|
Fired when a session is created.
|
SessionExpiredEvent
|
Fired when a session expires.
|
SessionGetAttributeEvent
|
Fired when a session attribute is requested.
|
SessionInvalidatedEvent
|
Fired when a session is invalidated.
|
SessionSetAttributeEvent
|
Fired when a session attribute is setted.
|